# Remote Access

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**RDP** (Remote Desktop Protocol) is a graphical remote desktop connection method. A Windows host can use the built-in Remote Desktop Connection tool to access the Debian desktop of a Quectel Pi development board (M1/L1), and view or control the graphical interface remotely.

Quectel Pi M1 mainly uses the **GNOME** desktop environment and already integrates GNOME Remote Desktop, so VNC, Xvfb, x11vnc, or similar software does not need to be installed separately. Quectel Pi L1 currently uses the **Weston** graphical environment and can provide a remote desktop service through Weston's built-in **RDP backend**.

```{note}
When using RDP remote desktop on M1, keep the graphical desktop session logged in. For L1 RDP, Weston `rdp-backend.so` is recommended.
```

# Preparation

1. **Confirm the device environment:**  
    - Quectel Pi M1 / L1 has booted into the Debian system.  
    - The Windows host and development board are reachable on the same network segment or the same LAN.  
    - The Remote Desktop Connection tool is installed or enabled on the Windows host.

2. **It is recommended to access the development board through the serial port.** For detailed serial port connection instructions, refer to debug_uart.md. For M1, use the account and password created during setup as prompted. For L1, log in as the `root` user by default, with no password. If the local debugging environment is already available, you can also enter the system through ADB (L1).

3. **Obtain the device IP address.** Run the following command on the development board:

```bash
hostname -I
```

Record the IP address on the current network. This address is required when connecting from Windows Remote Desktop later.

> 💡 Note: The Windows host and development board must be on the same network segment or same LAN, and the network must be reachable in both directions. Otherwise, even if the RDP service has started on the board, the connection cannot be established normally.

If you plan to start the RDP service with the normal user `q` (L1), create the user and set the password first:

```bash
adduser --disabled-password --gecos "" q
echo 'q:q' | chpasswd
```

If a usable normal user already exists in the system, reuse the existing user and do not create it again.

# M1: GNOME Remote Desktop

## Software Installation

The GNOME desktop environment in the Quectel Pi M1 Debian system already integrates remote desktop-related functions. In general, VNC, Xvfb, x11vnc, or similar software does not need to be installed separately.

Run the following command in a terminal to check whether the remote desktop management tool exists:

```bash
which grdctl
```

If the command returns `/bin/grdctl`, the system already includes the GNOME Remote Desktop management tool.

## Software Configuration

1. **Enter the remote desktop settings page.** In the Quectel Pi M1 graphical interface, go to: Settings > System > Remote Desktop.

2. **Enable remote desktop.** In the remote desktop settings page, enable the following switches as needed:  
    - **Desktop Sharing**: Allows other devices to view the current desktop through the RDP protocol.  
    - **Remote Control**: Allows the remote endpoint to control the mouse and keyboard.

```{image} images/image_Nvc4b4MlVoqi9uxrTllcEgcbnhb.webp
:width: 1280px
:height: 800px
```

1. **View connection information.** In the remote desktop settings page, view the host name for identifying the device on the LAN, port, default RDP port `3389`, username, and password. To change the login password, click the edit button next to the password field and reset it as prompted by the UI.

## Keep the Remote Desktop Login Password

If the login password is modified only on the Remote Desktop page in system settings, it may need to be set again after the device reboots or the user logs in again. To keep the remote desktop login password available, modify the `Login` keyring password through the **Passwords and Keys** tool.

1. Open **Utilities** in the application list, and click **Passwords and Keys**.

```{image} images/image_Y2ztbKUetoTYV5xUPF2cMQaOnMg.webp
:width: 1280px
:height: 800px
```

1. In the **Passwords** category, select `Login`, right-click the remote desktop credential, and select **Change Password**.

```{image} images/image_NrYkbUnLrop32gxcRBvcUItCn8f.webp
:width: 1280px
:height: 800px
```

1. Enter the old password. The old password is the remote login password configured earlier in the remote desktop settings, for example `q` in this test environment.

```{image} images/image_UKaMbWK3coY1cJxnF9vc4LAFnGc.webp
:width: 1280px
:height: 800px
```

1. Set the new `Login` keyring password. If you want the system to automatically read remote desktop credentials after login, leave the new password empty and click **Continue**.

2. If the new password is left empty, the system prompts that the password will be stored unencrypted. Confirm and click **Continue**.

```{image} images/image_Gf1cbnqlMoH5eGx5sw8cm11dnsd.webp
:width: 1280px
:height: 800px
```

```{note}
Setting the `Login` keyring password to empty reduces credential security and is recommended only in development and debugging environments. If the device is used in production or shared by multiple users, use a non-empty password and manually unlock the keyring when needed.
```

# Software Startup

After **Desktop Sharing** is enabled in the graphical interface, the GNOME Remote Desktop service is automatically enabled.

You can also use the following command in the terminal to view the current status:

```bash
grdctl status --show-credentials
```

Normally, RDP-related status, port, username, and remote control mode can be viewed.

To enable the RDP backend from the command line, run:

```bash
grdctl rdp enable
```

To allow the remote endpoint to control the mouse and keyboard, run:

```bash
grdctl rdp disable-view-only
```

To allow the remote endpoint to view the desktop only and not control the mouse or keyboard, run:

```bash
grdctl rdp enable-view-only
```

```{note}
In actual use, it is recommended to complete configuration through the graphical interface first to avoid inconsistency between command-line configuration and the UI display state.
```

# L1: Weston RDP Backend

## Software Installation

Check whether Weston supports the RDP backend:

```bash
env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --help | grep -i rdp
find /usr/lib* -name 'rdp-backend.so' 2>/dev/null
```

If `rdp-backend.so` is found, the current system includes the Weston RDP backend.

```{note}
The `weston` in the current Quectel Pi L1 image depends on runtime libraries under `/opt/qcom/lib`. If running `weston` directly reports `libweston-10.so.0: cannot open shared object file`, add `LD_LIBRARY_PATH=/opt/qcom/lib:/lib` before the command.
```

# Software Configuration

### Configure RDP Certificates

Weston RDP backend requires a TLS certificate and private key. Select the certificate location according to the startup user.

If the RDP service is started as `root`, generate certificates under `/etc/weston`:

```bash
mkdir -p /etc/weston
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /etc/weston/rdp.key \
  -out /etc/weston/rdp.crt \
  -days 365 \
  -subj "/CN=quectel-pi-l1"
chmod 600 /etc/weston/rdp.key
chmod 644 /etc/weston/rdp.crt
```

If the RDP service is started as normal user `q`, generate certificates under `/home/q`:

```bash
mkdir -p /home/q
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /home/q/weston-rdp.key \
  -out /home/q/weston-rdp.crt \
  -days 365 \
  -subj "/CN=quectel-pi-l1"
chown q:q /home/q/weston-rdp.key /home/q/weston-rdp.crt
chmod 600 /home/q/weston-rdp.key
chmod 644 /home/q/weston-rdp.crt
```

If a usable certificate already exists in the system, reuse the existing certificate path.

# Software Startup

## Recommended Method: Share the Current Physical Screen

If you want the RDP connection to show the same Weston screen displayed on the local MIPI/HDMI panel, enable Weston's `screen-share.so` module. This method lets the local Weston automatically start the RDP sharing process, and is suitable for remotely viewing and operating the current physical screen.

Run the following command to modify `/etc/xdg/weston/weston.ini`:

```bash
python3 - <<'PY'
from pathlib import Path

p = Path("/etc/xdg/weston/weston.ini")
s = p.read_text()

s = s.replace("#modules=screen-share.so", "modules=screen-share.so")
s = s.replace("--rdp-tls-cert=/data/misc/display/tls.crt", "--rdp-tls-cert=/etc/weston/rdp.crt")
s = s.replace("--rdp-tls-key=/data/misc/display/tls.key", "--rdp-tls-key=/etc/weston/rdp.key")
s = s.replace("start-on-startup=false", "start-on-startup=true")

p.write_text(s)
PY
```

After modification, reboot the system:

```bash
reboot
```

After the system reboots, check the Weston and RDP sharing processes:

```bash
ps -ef | grep weston
netstat -ltnp | grep 3389
cat /tmp/weston-rdp-share.log
```

If processes similar to the following are shown, local Weston has automatically started RDP sharing:

```
weston --idle-time=0 --log=/tmp/weston.log --config=/etc/xdg/weston/weston.ini --tty=1
weston --backend=rdp-backend.so --no-config --shell=fullscreen-shell.so --no-clients-resize --address=0.0.0.0 --rdp-tls-cert=/etc/weston/rdp.crt --rdp-tls-key=/etc/weston/rdp.key --log=/tmp/weston-rdp-share.log
```

At this point, the Windows host can directly use Remote Desktop to connect to the development board IP address. This method shares the current physical screen and does not require manually running `weston --backend=rdp-backend.so` again.

```{note}
The `screen-share` method depends on the `[screen-share]` section in the local Weston configuration. If the certificate paths are different in the system, replace `/etc/weston/rdp.crt` and `/etc/weston/rdp.key` in the command with the actual paths.
```

## Temporarily Start the RDP Service

Weston RDP backend can also be temporarily started as `root` or normal user `q` to provide an independent RDP desktop:

- Start as `root`: suitable for quick verification in the initial L1 environment after logging in as root through the serial port.

- Start as `q`: suitable for daily use after a normal user has been created.

This method creates a new Weston RDP desktop and does not mirror the local MIPI/HDMI physical screen. If you need to remotely share the current physical screen, use the `screen-share` method in the previous section first.

Only start one Weston RDP instance at a time. Do not run multiple startup commands at the same time, otherwise they will compete for port `3389`.

### Start as root

Foreground startup:

```bash
env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --backend=rdp-backend.so \
  --socket=wayland-rdp-root \
  --idle-time=0 \
  --rdp-tls-cert=/etc/weston/rdp.crt \
  --rdp-tls-key=/etc/weston/rdp.key \
  --width=1280 \
  --height=800
```

Background startup:

```bash
nohup env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --backend=rdp-backend.so \
  --socket=wayland-rdp-root \
  --idle-time=0 \
  --rdp-tls-cert=/etc/weston/rdp.crt \
  --rdp-tls-key=/etc/weston/rdp.key \
  --width=1280 \
  --height=800 \
  >/tmp/weston-rdp.log 2>&1 &
```

### Start as a normal user

Prepare the runtime directory before startup. If you have already logged in as user `q`, skip the `chown` command. If the current user is `root`, run the complete commands below:

```bash
mkdir -p /run/user/1007
chown q:q /run/user/1007
chmod 700 /run/user/1007
```

Run the following commands as user `q`. If the current prompt already starts with `q@...`, run them directly and do not add `runuser -u q --`.

`runuser -u q --` is used only when the current login user is `root`, to temporarily switch from a root shell to user `q` for the following command. If you are already logged in as user `q`, adding `runuser -u q --` may fail because the environment does not contain that command.

Foreground startup:

```bash
env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800
```

Background startup:

```bash
nohup env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800 \
  >/tmp/weston-rdp.log 2>&1 &
```

If the current user is `root`, you can also add `runuser -u q --` before `env -i` in the startup command above to start the RDP service as user `q`. Example:

```bash
runuser -u q -- env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800
```

Check RDP port listening:

```bash
netstat -ltnp | grep 3389
```

If output similar to the following is shown, the RDP service has started:

```
tcp        0      0 0.0.0.0:3389            0.0.0.0:*               LISTEN      <PID>/weston
```

### Stop the RDP Service

To stop a temporarily started Weston RDP service, run:

```bash
pkill -f 'weston.*rdp-backend'
```

# Remote Desktop Connection

1. Open Remote Desktop Connection on the Windows host.

2. Enter the development board IP address in the Computer input field, for example `10.66.84.106`. To manually specify a port, enter `10.66.84.106:3389`.

```{image} images/image_Qajcbj8sRobK6RxwgXqc1ecanyf.webp
:width: 475px
:height: 286px
```

1. Click **Connect**, and enter the username and password shown in the remote desktop settings page as prompted. If Windows Security asks for credentials, click **More choices**, select **Use a different account**, and enter the username and password configured in the remote desktop settings page.

```{image} images/image_LTb8bONgYoTv67xzfvsc5iVvnRb.webp
:width: 456px
:height: 580px
```

1. After the connection succeeds, you can view and operate the Debian desktop from the Windows host. After L1 is connected successfully, you can remotely view and operate the Weston RDP desktop.

```{image} images/image_IfuPbcLuLoemPwxDGnMcO5benHg.webp
:width: 1280px
:height: 823px
```

```{image} images/image_A4BWbKVQXo5on0xl5EvccBFNnwg.webp
:width: 963px
:height: 459px
```

# Troubleshooting

| **Symptom** | **Possible Cause** | **Solution** |
| --- | --- | --- |
| No output from `weston --help \| grep -i rdp` (L1) | Weston was not compiled with or does not include the RDP backend | Check whether `/usr/lib/libweston-*/rdp-backend.so` exists in the system |
| `weston --help` or RDP startup reports `libweston-10.so.0: cannot open shared object file` (L1) | The dynamic library path required by Weston is not set | Add `LD_LIBRARY_PATH=/opt/qcom/lib:/lib` before running Weston-related commands |
| Startup reports a certificate or private key error (L1) | Certificate path is incorrect, the file does not exist, or the private key permissions are incorrect | Confirm that `--rdp-tls-cert` and `--rdp-tls-key` point to valid files |
| No output from `netstat -ltnp \| grep 3389` (L1) | Weston RDP backend did not start successfully | Check error messages in `/tmp/weston-rdp.log` |
| Windows Remote Desktop cannot connect (L1) | No reachable IP, port 3389 is not listening, or the network is unreachable | Run `hostname -I` and `netstat -ltnp \| grep 3389` on L1, and confirm that Windows and L1 can reach each other |
| A certificate is reported as untrusted during connection (L1) | A local self-signed certificate is used | Confirm that the IP is correct and continue, or replace it with a trusted certificate |
| Windows Remote Desktop cannot connect (M1) | The Windows host and M1 are not on the same LAN | Confirm both network connections and obtain the M1 IP address again |
| Windows Remote Desktop cannot connect (M1) | IP address or port is incorrect | Run `hostname -I` on M1 to confirm the IP. Use the default port `3389` |
| Windows Remote Desktop cannot connect (M1) | **Desktop Sharing** is not enabled | Go to `Settings > System > Remote Desktop` and enable **Desktop Sharing** |
| Desktop can only be viewed and the mouse/keyboard cannot be controlled (M1) | **Remote Control** is not enabled, or the current mode is view-only | Enable **Remote Control**, or run `grdctl rdp disable-view-only` |
| Login reports incorrect username or password (M1) | The entered credentials do not match those shown in the remote desktop settings | Use the username and password shown in the remote desktop settings page. Regenerate or manually modify the password if needed |
| Remote desktop password becomes invalid after reboot or re-login (M1) | The `Login` keyring did not keep the remote desktop credential | Modify the `Login` keyring password according to the Keep the Remote Desktop Login Password section |
| Display is abnormal or does not refresh after connection (M1) | The graphical desktop session state is abnormal | Confirm that M1 has logged in to the graphical desktop, disconnect, and reconnect |
| Cannot connect after network switching (L1/M1) | The device IP address changed | Run `hostname -I` again to obtain the current IP address, and update the connection address in Windows Remote Desktop |